6.2 `--agents` - 动态定义自定义子代理

--agents 标志允许您通过 JSON 动态定义自定义子代理，无需修改配置文件。这为临时或特定任务提供了灵活的代理配置方式。

标志语法#

bash
复制
claude --agents '<json>' [其他选项]

功能描述#

--agents 标志接受定义一个或多个自定义子代理的 JSON 对象。每个子代理需要一个唯一的名称（作为键）和一个具有以下字段的定义对象：

使用示例#

基本用法#

bash
复制

claude --agents '{
  "reviewer": {
    "description": "Reviews code",
    "prompt": "You are a code reviewer"
  }
}'

定义一个简单的代码审查子代理。

多个子代理#

bash
复制

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

定义多个子代理，每个有不同的职责和配置。

指定工具#

bash
复制

claude --agents '{
  "tester": {
    "description": "Runs and analyzes tests",
    "prompt": "You are a testing expert. Run tests and analyze failures.",
    "tools": ["Bash", "Read", "Grep"]
  }
}'

定义一个只能使用特定工具的子代理。

指定模型#

bash
复制

claude --agents '{
  "analyzer": {
    "description": "Analyzes code structure",
    "prompt": "You are a code architecture expert.",
    "model": "opus"
  }
}'

定义一个使用特定模型的子代理。

使用场景#

1. 代码审查#

bash
复制

claude --agents '{
  "reviewer": {
    "description": "Reviews code for quality and security",
    "prompt": "You are a security-focused code reviewer."
  }
}' "审查这段代码"

使用专门的代码审查子代理。

2. 调试#

bash
复制

claude --agents '{
  "debugger": {
    "description": "Debugs errors and failures",
    "prompt": "You are an expert debugger."
  }
}' "调试这个错误"

使用专门的调试子代理。

3. 测试#

bash
复制

claude --agents '{
  "tester": {
    "description": "Runs and analyzes tests",
    "prompt": "You are a testing expert."
  }
}' "运行测试并分析结果"

使用专门的测试子代理。

4. 文档生成#

bash
复制

claude --agents '{
  "documenter": {
    "description": "Generates documentation",
    "prompt": "You are a technical writer."
  }
}' "为这个 API 生成文档"

使用专门的文档生成子代理。

子代理的优势#

1. 专业化#

每个子代理可以专注于特定领域：

• 代码审查
• 调试
• 测试
• 文档生成

2. 灵活性#

可以动态定义子代理，无需修改配置文件：

• 临时任务
• 特定项目
• 实验性功能

3. 工具限制#

可以限制子代理使用的工具：

• 提高安全性
• 减少成本
• 优化性能

4. 模型选择#

可以为每个子代理选择不同的模型：

• 使用更强大的模型处理复杂任务
• 使用更快的模型处理简单任务
• 优化成本和性能

注意事项#

1. JSON 格式：确保 JSON 格式正确，使用单引号或转义双引号
2. 唯一名称：每个子代理必须有唯一的名称
3. 描述清晰：描述应该清晰明确，帮助 Claude 决定何时调用
4. 提示有效：系统提示应该清晰具体，指导子代理的行为
5. 工具兼容：指定的工具必须存在且可用
6. 模型有效：指定的模型必须受支持

最佳实践#

1. 明确描述：子代理描述应该明确说明何时应该调用
2. 具体提示：系统提示应该具体指导子代理的行为和风格
3. 合理工具：只包含子代理实际需要的工具
4. 合适模型：根据任务复杂度选择合适的模型
5. 测试验证：定义子代理后，测试其行为是否符合预期
6. 文档记录：记录每个子代理的用途和配置

与配置文件的对比#

常见问题#

Q: 可以定义多少个子代理？#

A: 理论上没有限制，但过多的子代理可能影响性能和决策。

Q: 子代理可以嵌套吗？#

A: 不可以，子代理不能调用其他子代理。

Q: 子代理的提示可以多长？#

A: 提示长度有限制，建议保持简洁明确。

Q: 如何调试子代理？#

A: 使用 --verbose 标志可以查看子代理的调用和执行详情。

相关资源#

• 子代理文档：详细的子代理配置和使用指南
• --model：设置会话模型
• --verbose：启用详细日志记录

实际应用示例#

项目特定子代理#

bash
复制
#!/bin/bash
# 为项目定义特定的子代理
claude --agents '{
  "api-reviewer": {
    "description": "Reviews API endpoints for REST best practices",
    "prompt": "You are an API design expert. Focus on REST principles, error handling, and documentation."
  },
  "database-expert": {
    "description": "Optimizes database queries and schema",
    "prompt": "You are a database performance expert. Focus on query optimization and indexing."
  }
}' "审查这个 API 设计"

临时调试会话#

bash
复制
#!/bin/bash
# 创建临时调试会话
claude --agents '{
"debugger": {
"description": "Debugs the current issue",
"prompt": "You are a debugging specialist. Analyze the error, identify the root cause, and provide a fix.",
"model": "opus"
}
}' --verbose "调试这个生产问题"